package com.googlecode.continuity.core.client;

import java.util.Date;
import java.util.Set;

/**
 * The ContinuityUser interface is a central part of Continuity, defining various aspects of how a user object can be
 * accessed.  This includes general information (such as name, email, id) as well as methods providing the most basic
 * security level in Continuity, the authority system.
 *
 * @author Peter Schmitt <aragos@aragos.de>
 * @see User
 */
public interface ContinuityUser {
// -------------------------- OTHER METHODS --------------------------

  /**
   * Returns the set of authorities this user posseses.
   *
   * @return this user's authorities
   */
  Set getAuthorities();

  /**
   * Returns this user's email address.
   *
   * @return this user's email address
   */
  String getEmail();

  /**
   * Returns this user's unique id.
   *
   * @return this user's unique id
   */
  int getId();

  /**
   * Returns the date and time on which this user last logged into the system. Can be null if no login has occured so
   * far.
   *
   * @return date of this user's last login or null if no login occurred
   */
  Date getLastSeen();

  /**
   * Returns the date and time on which this user registered with the system.
   *
   * @return the date and time on which this user registered with the system
   */
  Date getRegistered();

  /**
   * Returns this user's name.
   *
   * @return this user's name
   */
  String getUsername();

  /**
   * Grants an authority to this user by adding it to the user's set of authorities.
   *
   * @param auth newly granted authority
   */
  void grantAuthority(GrantedAuthority auth);

  /**
   * Returns <code>true</code> if this user has been granted the authority described by the role description.
   *
   * @param roleDescription string-ified description of this the authority
   * @return <code>true</code> if this user has been granted the authority described by the given description
   * @see com.googlecode.continuity.core.client.GrantedAuthority
   */
  boolean hasAuthority(String roleDescription);

  /**
   * Revokes an authority from this user by removing it from the user's set of authorities.
   *
   * @param auth authority to be revoked
   */
  void revokeAuthority(GrantedAuthority auth);

  /**
   * Sets a new email address for this user.
   *
   * @param email user's new email address
   */
  void setEmail(String email);

  /**
   * Sets the date and time of this user's most recent login.
   *
   * todo: remove?
   *
   * @param lastSeen date and time for this user's most recent login
   */
  void setLastSeen(Date lastSeen);

  /**
   * Sets the date and time of this user's registration.
   *
   * todo: remove?
   *
   * @param registered date and time of this user's registration
   */
  void setRegistered(Date registered);
}
